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PREFACE 


Manual Objectives 

This manual explains how to install, verify, and manage VAX LISP/VMS. 


Intended Audience 

If you are responsible for installing and maintaining the VAX LISP 
software product, you should read this manual. To perform the 
installation, you must have access to a privileged system manager's 
account and be familiar with VAX/VMS installation procedures for 
layered products. 


Structure of This Manual 

The manual is divided into three chapters and one appendix: 

• Chapter 1, Preparing for the Installation, describes the 
prerequisites for installing and verifying VAX LISP. 

• Chapter 2, Installation and Verification, explains the 
procedure for installing and verifying VAX LISP. 

• Chapter 3, Completing the Installation, gives information 
needed to complete the installation. 

• The Appendix, Problem Determination and Reporting, shows how 
to report a defect in the product. 


Conventions 

Convention Meaning 

UPPERCASE characters In examples, indicate that you should 

type the word or letter exactly as shown. 
For example: 

$ RUN SYS$SYSTEM:SYSGEN 
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PREFACE 


Convention Meaning 

lowercase italics In examples, italics indicate that you 

are to substitute a word or value of your 
choice. For example: 

UAF> MODIFY user-name /PGFLQUOTA =value 

Red print in examples, indicates user input. For 

example: 

INSTALL> /LIST/GLOBAL/SUMMARY 

Black print In examples, indicates output lines or 

prompting characters that the system 
displays. For example: 

SYSGEN> SHOW GBLSECTIONS 
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CHAPTER 1 


PREPARING FOR THE INSTALLATION 


Before you install the VAX LISP/VMS language, you should be familiar 
with: 

• VAX LISP naming conventions 

• Contents of the distribution Kit 

• VAX/VMS system management 

• VAX LISP/VMS installation prerequisites 


1.1 VAX LISP NAMING CONVENTIONS 

VAX LISP is implemented on both the VMS and the ULTRIX-32 operating 
systems. VAX LISP as implemented on the VMS operating system is 
formally named VAX LISP/VMS. VAX LISP as implemented on the ULTRIX 
operating system is formally named VAX LISP/ULTRIX. VAX LISP/VMS and 
VAX LISP/ULTRIX are the same language, but with some specific 
operating system differences. For the differences, see the VAX 
LISP/VMS Release Notes described in Section 1.2.2. 

This manual describes VAX LISP/VMS but refers to VAX LISP/VMS as VAX 
LISP whenever possible. 


1.2 CONTENTS OF THE DISTRIBUTION KIT 

The VAX LISP/VMS distribution kit contains seven manuals and one 
distribution volume. 
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1.2.1 Documentation 

The seven manuals in the distribution kit are: 

• COMMON LISP: The Language by Guy Steele 

• VAX LISP/VMS Editor Programming Guide 

• VAX LISP/VMS Graphics Programming Guide 

• VAX LISP/VMS Installation Guide (this manual) 

• VAX LISP/VMS System Access Programming Guide 

• VAX LISP/VMS System-Building Guide 

• VAX LISP/VMS User's Guide 


1.2.2 Software 

The distribution volume contains the files for the VAX LISP product in 
four savesets: 


LISPnnn.A 
LISPnnn.B 

LISPnnn.C 
LISPnnn.D 


Installation procedure and release notes 
LISP executable image, on-line documentation, 
and Installation Verification Procedure 
Examples of LISP source code 
System-Building utility libraries 


where nnn is the VAX LISP version number. When you finish the 
installation procedure, these files are installed in your system in 
the following way: 


• The system manager's directory (SYS$MANAGER) will contain the 
files LISPSTART.COM and LISPSITE.COM. 

• The system help directory (SYS$HELP) will contain the release 
notes in the file LISPnnn.RELEASE_NOTES where nnn is the VAX 
LISP version number. For example, file LISP020.RELEASE_NOTES 
contains the release notes for VAX LISP, Version 2.0. 

• The product directory {SYS$SYSR00T:[VAXLISP] by default) will 
contain: 

LISP.EXE LISP executable image 

LISPDOC.TLB LISP on-line documentation library 

LISPIVP.COM Installation Verification Procedure (IVP) 
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• The EXAMPLES subdirectory of the product directory will con¬ 
tain sample LISP source files. 

• The LIBRARY subdirectory of the product directory will contain 
the System-Building utility files. 


1.3 VAX/VMS SYSTEM MANAGEMENT 

For information on system installation, utilities, operation, and man¬ 
agement not covered by the VAX LISP/VMS documentation, see the 
appropriate VMS documentation. If you are installing VAX LISP on the 
VMS operating system, the following documents may be useful: 

• Guide to VAX/VMS System Management and Daily Operations 
m Guide to VAX/VMS Software Installation 

• VAX/VMS Utilities 

For a complete list of VAX/VMS documents, see the VAX/VMS Master 
Index . 

If you are installing VAX LISP on the MicroVMS operating system, see 
the MicroVMS User's Manual. 


1.4 VAX LISP/VMS INSTALLATION PREREQUISITES 

Before you begin the installation procedure, make sure you have the 
necessary software, documentation, and prerequisites. The prerequi¬ 
sites listed below are the minimum amounts needed to install VAX LISP. 
The installation procedure will fail if any of these parameters are 
below the required value. 

If you have an AI VAXstation, you may want more than the minimum 
number for your virtual page count and user authorization quotas. The 
recommended values may be set before or after the installation. See 
Section 3.3 for recommended system parameters and authorization quotas 
on a typical AI VAXstation. 

Prerequisites: 

• Access to the system manager's account. 

• A valid VAX/VMS operating system configuration with VAX/VMS 
V4.4 or later. 

• Adequate amounts or values for: 
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System disk blocks 

Global pages (GBLPAGES) and sections (GBLSECTIONS) 

- Virtual page count (VIRTUALPAGECNT) 

User authorization quotas 
User disk block quota 

The following sections explain all but the first two prerequisites. 

NOTE 

If you modify any of the SYSGEN parameters in 
SYS$SYSTEM:MODPARAMS.DAT (Section 3.3.1), you must run 
the AUTOGEN utility to re-compute your system 
parameters. To do so, enter the following command: 

$@SYS$UPDATE:AUTOGEN SAVPARAMS REBOOT 

Since these parameters are not dynamic, your system 
will then need to be rebooted. AUTOGEN will perform 
an automatic shutdown and reboot when it has finished. 

For details on using the AUTOGEN utility, see Chapter 
11 of the Guide to VAX/VMS System Management and Daily 
Operations . For detailed descriptions of the SYSGEN 
parameters, see the VAX/VMS Utilities . 


1.4.1 System Disk Blocks 

The installation of VAX LISP/VMS requires approximately 60,000 free 
blocks on the system disk. After the installation, approximately 
30,000 blocks on the disk containing the product directory are 
occupied. Saveset B occupies approximately 11,500 blocks; saveset C, 
approximately 5,000; and saveset D, approximately 13,500. 


1.4.2 Global Pages (GBLPAGES) and Sections (GBLSECTIONS) 

You need approximately 5060 global pages and 4 global sections to 
install the VAX LISP/VMS image LISP.EXE and to make it shareable. You 
may need to adjust the values of the system generation (SYSGEN) 
parameters GBLPAGES and GBLSECTIONS before installing LISP.EXE. 

To determine the current value of GBLSECTIONS and GBLPAGES, enter the 
following SYSGEN utility commands: 
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$ RUN SYS$SYSTEM:SYSGEN 
SYSGEN> SHOW GBLSECTIONS 
SYSGEN> SHOW GBLPAGES 

Note the values that are displayed. 

Next, you must determine how many global pages and global sections are 
actually in use on your system. To do so, type CTRL/Z to leave the 
SYSGEN utility, and enter the commands: 

$ INSTALL :== $SYS$SYSTEM:INSTALL /COMMAND_MODE 
$ INSTALL 

INSTALL> LIST/GLOBAL/SUMMARY 

These commands display "Global Sections Used" and "Global Pages Used." 
Take these values and subtract them from the values you previously 
obtained from the SYSGEN utility. If you do not have enough global 
sections and global pages, you must modify the GBLSECTIONS and/or 
GBLPAGES parameters. 

To modify these values, edit SYS$SYSTEM:MODPARAMS.DAT to include the 
lines: 


ADD_GBLPAGES=5060 
ADD GBLSECTI0NS=4 


NOTE 

Using the ADD_ prefix with these parameters increases 
them by the amount you supply in each subsequent 
GENPARAMS phase of AUTOGEN. After many executions of 
AUTOGEN, parameters can become undesirably large. You 
can avoid this problem by commenting out the ADD_ 
lines in MODPARAMS.DAT after the first execution of 
the GENPARAMS phase of AUTOGEN. 


1.4.3 Virtual Page Count (VIRTUALPAGECNT) 

The default VAX LISP product requires approximately eight megabytes of 
address space. In addition, the value of the SYSGEN parameter 
VIRTUALPAGECNT must be approximately 16,000 virtual pages for VAX LISP 
to execute. This value must be larger if you want to increase the 
size of the LISP system's dynamic memory with the LISP/MEMORY command. 
(See the VAX LISP User's Guide for a description of the LISP/MEMORY 
command.) 
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NOTE 

If you increase the virtual page count, you may also 
need to increase the size of your paging file. You 
can display statistics about your paging file use with 
the DCL command SHOW MEMORY/FILES. 


To determine the current value of VIRTUALPAGECNT, enter the SYSGEN 
utility commands: 

$ RUN SYS$SYSTEM:SYSGEN 
SYSGEN> SHOW VIRTUALPAGECNT 

To modify these values, edit SYS$SYSTEM:MODPARAMS.DAT to include a 
line in the following format: 

VIRTUALPAGECNT=value 


1.4.4 User Authorization Quotas 

The system manager's account and accounts for VAX LISP users must have 
adequate user authorization quotas for paging files and working sets. 
These quotas (PGFLQUOTA, WSQUOTA, and WSEXTENT) are set with the 
AUTHORIZE utility. To invoke the AUTHORIZE utility, specify the 
following commands: 

$ SET DEFAULT SYS$SYSTEM 

$ RUN AUTHORIZE 

UAF> 


NOTE 

When the system manager changes a user authorization 
quota (including the system manager's own quota) with 
the AUTHORIZE utility, the quota is not changed until 
the user logs out of the system and then logs back in. 


Once you have invoked the AUTHORIZE utility, you can set each of the 
quotas with the commands below. To leave the AUTHORIZE utility, type 
EXIT or CTRL/Z. 


• Paging file quota (PGFLQUOTA) 

A VAX LISP user requires a minimum paging file quota of 10,500 
pages. However, this quota must be larger if users want to 
increase the size of the LISP system's dynamic memory with the 
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LISP/MEMORY command. See the VAX LISP User's Guide for a 
description of the LISP/MEMORY command. 

Use the following format to change a user's paging file quota: 

UAF> MODIFY user-name /PGFLQUOTA=value 
Example: 

UAF> MODIFY JONES /PGFLQUOTA=20000 


• Working set quota (WSQUOTA) 

The amount of physical memory required to execute a LISP 
program depends on the nature of the program. DIGITAL 
recommends that each LISP user doing development work have a 
minimum working set quota of 1500 pages of physical memory. 
Use the following format to change this quota: 

UAF> MODIFY user-name /WSQUOTA =value 

Example: 

UAF> MODIFY JONES /WSQUOTA=1500 


• Working set extent quota (WSEXTENT) 

The WSEXTENT quota allocates the amount of physical memory 
given to a process when the system has an excess of free 
pages. Use the following format to change this quota: 

UAF> MODIFY user-name /WSEXTENT=value 

Example: 

UAF> MODIFY JONES /WSEXTENT=1 0000 


1.4.5 User Disk Block Quota 

VAX LISP provides a facility that enables users to suspend LISP 
operation and continue it later (see the VAX LISP User's Guide for an 
explanation of suspended systems). Since a suspended LISP system 
requires a large amount of disk space, users may need increased disk 
quotas. You can change these quotas with the DISKQUOTA utility. To 
enter that utility, type the command: 

$ RUN SYS$SYSTEM:DISKQUOTA 
DISKQ> 


1-7 



PREPARING FOR THE INSTALLATION 


To leave the DISKQUOTA utility, type EXIT or CTRL/Z. When you are in 
the DISKQUOTA utility, use the following format to change a user disk 
quota: 

DISKQ> MODIFY U1C [/PERMQUOTA=guo ta ] 

[/OVERDRAFT=guota-pIus] 

Example: 

DISKQ> MODIFY [300,211] /PERMQUOTA=20000 
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INSTALLATION AND VERIFICATION 


This chapter explains how to use the VMSINSTAL procedure to install 
VAX LISP/VMS and to verify the installation. For a detailed 
description of the VMSINSTAL procedure, see the Guide to VAX/VMS 
Software Installation. 

Any system user who has access to the system manager's account or to 
an account with the same privileges as the system manager's account 
can perform the installation procedure. 

The VMSINSTAL procedure is automated and self-explanatory, and takes 
approximately 15 minutes (25 on a MicroVAX). The procedure prompts 
you to mount the software distribution volume and to respond to 
questions during the installation. Most of the questions can be 
answered with YES or NO. The default response is enclosed in square 
brackets [ ]. To choose the default response, just press the RETURN 
key. Or, enter your response and press the RETURN key. If you need 
help with a question, type a question mark (?) and press the RETURN 
key. 

It's a good idea to back up your system disk before installing any 
layered product. 


2.1 STARTING THE VMSINSTAL PROCEDURE 

To start the VMSINSTAL procedure: 

1. Make sure the installation prerequisites listed in Section 
1.4 have been met. The Guide to VAX/VMS Software Installa¬ 
tion describes all the VMSINSTAL prerequisites. 

2. Log into the system manager's account. 

Installations are usually done from the console terminal, but 
can be done from any terminal. 


2-1 



INSTALLATION AND VERIFICATION 


3. If a previous version of VAX LISP is installed, make sure you 
have edited your LISPSITE.COM procedure as described in 
Section 3.2.2. Pay particular attention to the notes in that 
section. 

4. Invoke the VMSINSTAL procedure by using a command of the 
form: 

$ @SYS$UPDATE:VMSINSTAL LISP device 

where device is the name of the device on which you must 
mount the VAX LISP distribution volume, such as MFAO or MUAO. 
When you specify a device name, type a colon (:) after the 
name. For example: 

$@SYS$UPDATE:VMSINSTAL LISP MFAO: 

After you invoke VMSINSTAL, the following messages are 
displayed on your output device: 

VAX/VMS Software Product Installation Procedure 
It is dd-mmm-yyyy at hh:nm 

Enter a question mark (?) at any time for help. 

You may receive warning messages from VMSINSTAL if, for 
example, your DECnet network is still up and running. Check 
the Guide to VAX/VMS Software Installation for VMSINSTAL 
error messages and recommended actions. Once all VMSINSTAL 
prerequisites are met, the procedure displays: 

Are you satisfied with the backup of your system disk 
[YES]? 

5. Respond to the backup question. If you are satisfied with 
the backup of your system disk, type YES (or press the RETURN 
key). If you are not satisfied, type NO and provide for a 
backup (see the Guide to VAX/VMS Software Installation ). If 
you type NO, the procedure ends. When you are ready, start 
again. 

If you type YES (or press the RETURN key), the installation 
starts. 


2.2 INSTALLING VAX LISP/VMS 

The installation consists of the following five steps: 

1. Purge files. 
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The installation procedure first reads the tape and displays 
the product(s) it contains: 

The following products will be processed: 

LISP V2.2 

Beginning installation of LISP V2.2 at hh:mm 
%VMSINSTAL-I-RESTORE, Restoring product saveset A... 
%VMSINSTAL-I-RELMOVED, The products release notes have 
been successfully moved to SYS$HELP. 

Next it asks whether you want to purge any files replaced 
during the course of the installation: 

Do you want to purge files replaced by this installation 
[YES]? 

Just press the RETURN key if you want to purge the old files, 
or enter NO if you want to keep them. (See also step 4, 
below, on saving the previous version.) 

The installation procedure now displays a help message 
explaining the contents of the savesets and your options for 
installing them. 

2. Select a saveset. 

The procedure now asks whether you want to install the next 
saveset on the tape, and displays the size of the saveset. 
On saveset B, for example, it asks: 

Do you wish to install the VAX LISP product files 
(11500 blocks) [YES]? 

Press the RETURN key if you do want to install the saveset. 
Enter NO if you do not. 

You can install all three savesets now, or you can install 
only the product files (the LISP executable image, on-line 
documentation library, and Installation Verification 
Procedure). Saveset B contains everything needed to run VAX 
LISP. You can install additional savesets at any time by 
running VMSINSTAL again and selecting different savesets. 

3. Specify location. 

You must now tell VMSINSTAL the desired location of the 
saveset you selected in step 2. Continuing with saveset B as 
the example: 

In which directory are the VAX LISP product files to be 
installed [SYS$SYSROOT:[VAXLISP]]? 
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Press the RETURN key if you are satisfied with the default 
directory, or enter a different location. If the directory 
you specify does not already exist, the procedure asks: 

Directory SYS$SYSROOT:[VAXLISP] does not exist. Should 
it be created [YES]? 


4. Save previous version. (optional) 

This step is not executed unless a previous version of VAX 
LISP is already installed in the default directory. 

VAX LISP users can create "suspended systems" that contain 
LISP programs and data. A suspended system depends on the 
version of VAX LISP used to create it. Since the installa¬ 
tion procedure overwrites any previous version of VAX LISP in 
the default directory, installing the new version makes user- 
created suspended systems unuseable. You may want to save 
your previous version of VAX LISP so that users can resume 
their suspended systems. 

To save the previous version of VAX LISP, you can allow the 
procedure to move it to another directory before you install 
the new version in SYS$SYSROOT[VAXLISP]. 

Do you want to save the previous version of VAX LISP 
(nnnn blocks) [NO] ? 

If you do not want to save your previous version, enter NO or 
press RETURN and skip the rest of this step. If you do want 
to save it, enter YES. The procedure now asks for a new 
location for VAX LISP: 

In which directory should the previous version be saved 
[VMI$ROOT:[VAXLISP.V021]]? 

Enter your own directory or just press RETURN to use the de¬ 
fault. (The default directory automatically includes the 
correct version number.) Again, if the directory does not 
exist, the procedure asks for confirmation: 

Directory VMI$ROOT:[VAXLISP.V021] does not exist. 

Should it be created [YES]? 

See Chapter 3 of this manual for directions on using the old 
version of VAX LISP after you have moved it out of 
SYS$SYSROOT:[VAXLISP]. 

Steps 2 and 3 repeat for each of the other savesets on the tape. 


2-4 



INSTALLATION AND VERIFICATION 


5. Verifying the installation. 

If you have selected saveset B, the last prompt asks whether 
you want to run the Installation Verification Procedure (IVP) 
after the installation is complete: 

Do you want to run the IVP after the installation [YES]? 

Press RETURN or enter YES only if you have properly confi¬ 
gured your system according to the prerequisites in Section 
1.4. See the next section for more information on the IVP. 

Once you have answered all its questions, the installation procedure 
copies the files. For example: 

%VMSINSTAL-I-SYSDISK, This product creates system disk directory 
SYS$SYSROOT:[VAXLISP]. 

%VMSINSTAL-I-RESTORE, Restoring product saveset B... 

%LISP-I-SITESTART, A skeleton site-specific startup procedure, 
LISPSITE.COM, 

-LISP-I-SITESTART, has been provided in SYS$MANAGER. 

%VMSINSTAL-I-MOVEFILES, Files will now be moved to their target 
directories. 

You may receive additional messages, depending on how many subsets you 
are installing and on your system configuration (for example, a VAX 
cluster or an AI VAXstation). 


2.3 VERIFYING THE INSTALLATION 

The IVP creates, compiles, and executes a small LISP program. Because 
VAX LISP will not run until you have properly configured your system, 
you cannot run the IVP if you have not already configured your system. 

During installation, the VMSINSTAL procedure asks if you want to run 
the IVP. If you have properly configured your system, type YES. The 
IVP runs, prints a message when the program has been completed, and 
the VMSINSTAL procedure automatically ends. If you type NO, VMSINSTAL 
ends without running the IVP. 

You may want only to install VAX LISP now and to configure your system 
later. Then, when you have properly configured your system, you can 
run the IVP by entering the following DCL command: 

@LISP$ SYSTEM: LISPIVP 
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2.4 TWO SAMPLE INSTALLATION PROCEDURES 

Two sample installation procedures follow. The first is a new instal¬ 
lation, and the second is an update installation. 


2.4.1 Sample New Installation 

This example illustrates the first installation of VAX LISP/VMS on a 
VAX. Since no previous version is present, the installation procedure 
does not ask whether you want to save it. 

$ @SYS$UPDATE:VMSINSTAL LISP MFAO: 


VAX/VMS Software Product Installation Procedure 

It is 10-APR-1987 at 16:10 

Enter a question mark (?) at any time for help. 

* Are you satisfied with the backup of your system disk [YES]? 
<RET> 

The following products will be processed: 

LISP V2.2 


Beginning installation of LISP V2.2 at 16:10 

%VMSINSTAL-I-RESTORE, Restoring product saveset A... 

%VMSINSTAL-I-RELMOVED, The products release notes have been 
successfully moved to SYS$HELP. 

* Do you want to purge files replaced by this installation [YES]? 
<RET> 

The LISP installation kit contains the VAX LISP product files, 
some example files, and some special library files for building 
customized LISP systems. It is possible to install just VAX 
LISP, and nothing else. It is also possible to install just the 
examples, or just the library files, or any combination of these. 

Enter YES to this question if you wish to install VAX LISP at 
this time. Enter NO to this question if you only wish to install 
the examples and/or library files at this time. 

* Do you wish to install the VAX LISP product files (11500 
blocks) [YES]? <RET> 

* In which directory are the VAX LISP product files to be 
installed [SYS$SYSROOT:[VAXLISP ] ] : <RET> 
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* Directory SYS$SYSROOT:[VAXLISP] does not exist. Should it be 
created [YES]? <RET> 

* Do you wish to install the VAX LISP examples (5000 blocks) 

[NO]? YES 

* In which directory are the VAX LISP examples to be installed 
[SYS$SYSROOT:[VAXLISP.EXAMPLES]]: <RET> 

* Directory SYS$SYSROOT:[VAXLISP.EXAMPLES] does not exist. 

Should it be created [YES]? <RET> 

* Do you wish to install the VAX LISP system-building library 
files (13500 blocks) [NO]? YES 

* In which directory are the VAX LISP system-building library 
files to be installed [SYS$SYSROOT:[VAXLISP.LIBRARY]]: <RET> 

* Directory SYS$SYSROOT:[VAXLISP.LIBRARY] does not exist. Should 
it be created [YES]? <RET> 

* Do you want to run the IVP after the installation [YES]? <RET> 

%VMSINSTAL-I-SYSDISK, This product creates system disk directory 

VMI$ROOT:[VAXLISP]. 

%VMSINSTAL-I-RESTORE, Restoring product saveset B... 

%LISP-I-SITESTART, A skeleton site-specific startup procedure, 
LISPSITE.COM, 

-LISP-I-SITESTART, has been provided in SYS$MANAGER. 

%VMSINSTAL-I-SYSDISK, This product creates system disk directory 
VMI$ROOT:[VAXLISP.EXAMPLES]. 

%VMSINSTAL-I-RESTORE, Restoring product saveset C... 

%VMSINSTAL-I-SYSDISK, This product creates system disk directory 
VMI$ROOT:[VAXLISP.LIBRARY]. 

%VMSINSTAL-I-RESTORE, Restoring product saveset D... 

%VMSINSTAL-I-MOVEFILES, Files will now be moved to their target 
directories. . . 

Executing VAX LISP startup procedure... 

VAX LISP Installation Verification Procedure (IVP) 

Starting compilation of file 
VMI$ROOT:[SYSUPD.LISP022]LISPIVP.LSP;1 

FIBONACCI compiled. 

PRINT-FIBONACCI compiled. 

Finished compilation of file 
VMI$ROOT:[SYSUPD.LISP022]LISPIVP.LSP;1 

0 Errors, 0 Warnings 

Welcome to VAX LISP, version V2.2 
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A table of the first 20 Fibonacci numbers: 


n 

Fibonacc 

0 

0 

1 

1 

2 

1 

3 

2 

4 

3 

5 

5 

6 

8 

7 

13 

8 

21 

9 

34 

10 

55 

11 

89 

12 

144 

13 

233 

14 

377 

15 

610 

16 

987 

17 

1,597 

18 

2,584 

19 

4,181 


$ 


VAX LISP V2.2 IVP Completed Successfully 
Installation of LISP V2.2 completed at 16:22 

VMSINSTAL procedure done at 16:22 


2.4.2 Sample Update Installation 

This example illustrates an update installation on a MicroVAX with 
Version 2.1 of VAX LISP/VMS already present. Version 2.1 will be 
saved to the directory VMI$ROOT[VAXLISP.V021]. Only the VAX LISP 
product files will be installed. 

$@SYS$UPDATE:VMSINSTAL LISP MUAO: 


VAX/VMS Software Product Installation Procedure 


It is 10-APR-1987 at 16:30 

Enter a question mark (?) at any time for help. 
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* Are you satisfied with the backup of your system disk [YES]? 
<RET> 

The following products will be processed: 

LISP V2.2 


Beginning installation of LISP V2.2 at 16:31 

%VMSINSTAL-I-RESTORE, Restoring product saveset A... 

%VMSINSTAL-I-RELMOVED, The products release notes have been 
successfully moved to SYS$HELP. 

* Do you want to purge files replaced by this installation [YES]? 
<RET> 

The LISP installation kit contains the VAX LISP product files, 
some example files, and some special library files for building 
customized LISP systems. It is possible to install just VAX 
LISP, and nothing else. It is also possible to install just the 
examples, or just the library files, or any combination of these. 

Enter YES to this question if you wish to install VAX LISP at 
this time. Enter NO to this question if you only wish to install 
the examples and/or library files at this time. 

* Do you wish to install the VAX LISP product files (11500 
blocks) [YES]? <RET> 

* In which directory are the VAX LISP product files to be 
installed [SYS$SYSROOT:[VAXLISP]]: <RET> 

* Do you want to save the previous version of VAX LISP (9151 
blocks) [NO]? YES 

* In which directory should the previous version be saved 
[VMI$ROOT:[VAXLISP.V021]]: <RET> 

* Directory VMI$ROOT:[VAXLISP.V021] does not exist. Should it be 
created [YES]? <RET> 

* Do you wish to install the VAX LISP examples (5000 blocks) 

[NO]? <RET> 

* Do you wish to install the VAX LISP system-building library 
files (13500 blocks) [NO]? <RET> 

* Do you want to run the IVP after the installation [YES]? <RET> 
%VMSINSTAL-I-SYSDISK, This product creates system disk directory 

VMI$ROOT:[VAXLISP.V021]. 

%VMSINSTAL-I-RESTORE, Restoring product saveset B... 

%VMSINSTAL-I-MOVEFILES, Files will now be moved to their target 
directories... 

Executing VAX LISP startup procedure... 

VAX LISP Installation Verification Procedure (IVP) 

Starting compilation of file 
VMI$ROOT:[SYSUPD.LISP022]LISPIVP.LSP;1 
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FIBONACCI compiled. 

PRINT-FIBONACCI compiled. 

Finished compilation of file 
VMI$ROOT: [ SYSUPD. LISP022 J LI SPI VP . LSP ; 1 
0 Errors, 0 Warnings 

Welcome to VAX LISP, version V2.2 

A table of the first 20 Fibonacci numbers: 


n 

Fibonacci 

0 

0 

1 

1 

2 

1 

3 

2 

4 

3 

5 

5 

6 

8 

7 

13 

8 

21 

9 

34 

10 

55 

11 

89 

12 

144 

13 

233 

14 

377 

15 

610 

16 

987 

17 

1,597 

18 

2,584 

19 

4,181 


VAX LISP V2.2 IVP Completed Successfully 
Installation of LISP V2.2 completed at 16:55 


VMSINSTAL procedure done at 16:55 




CHAPTER 3 


COMPLETING THE INSTALLATION 


To complete a new installation of VAX LISP/VMS, you must modify the 
site-specific system startup file, SYS$MANAGER:SYSTARTUP.COM. You 
should also modify the default site-specific startup file for VAX 
LISP, SYS$MANAGER:LISPSITE.COM. If you are installing VAX LISP on an 
AI VAXstation, read Section 3.3 on recommended system parameters and 
authorization quotas. Section 3.4 explains how to use a previous 
version of VAX LISP that has been moved out of the main directory. 


3.1 MODIFYING THE SYSTEM STARTUP FILE 

After the installation procedure is concluded, add the following line 
to your site-specific system startup file, SYS$MANAGER:SYSTARTUP.COM: 

$ @SYS$MANAGER:LISPSTART 

This command line invokes the VAX LISP system startup procedure every 
time you boot your system. The startup procedure defines the system 
logical name LISP$SYSTEM to mean the VAX LISP product directory and 
defines the logical name LISP$EXAMPLES to mean the examples directory. 


3.2 MODIFYING THE VAX LISP STARTUP FILE 

When you boot your VAX/VMS system, the file SYS$MANAGER:SYSTARTUP.COM 
invokes the LISP command file LISPSTART.COM, which in turn invokes the 
file SYS$MANAGER:LISPSITE.COM. This last command file is a default 
site-specific startup procedure for VAX LISP. 

This file includes default LISP system logical names and default 
commands for installing shareable sections. You should modify the 
logical name definitions to make them appropriate for your site. 
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If your VAX LISP system has only one user or if enough global pages 
are not available, you may not want to install LISP shareable. The 
benefit of installing shareable sections is that multiple users 
running VAX LISP use only one copy of the LISP system rather than a 
separate copy for each user, thereby saving valuable system resources. 

This skeleton LISPSITE.COM file will be installed in SYS$MANAGER, 
provided such a file is not already there: 

$! VAX LISP site-specific startup procedure. 

$! This procedure is invoked by the lispstart procedure. 

$! Remove comments and alter this file to suit your site. 

$ 

$ DEFINE/SYSTEM/EXECUTIVE LISP$TIME_ZONE 0 

$ DEFINE/SYSTEM/EXECUTIVE LISP$DAYLIGHT_SAVING_TIME_P NO 

$! DEFINE/SYSTEM/EXECUTIVE LISP$SHORT_SITE_NAME 

$1 DEFINE/SYSTEM/EXECUTIVE LISP$L0NG_SITE_NAME "?" 

$! DEFINE/SYSTEM/EXECUTIVE LISP$MACHINE_INSTANCE "?" 

$ 

$ SET NOON 

$! INSTALL := $SYS$SYSTEM:INSTALL /C0MMAND_M0DE 

$ 1 INSTALL CREATE LISP$SYSTEM:LISP/OPEN/HEADER_RESIDENT/SHARED 

$ SET ON 

$ EXIT 

You can add to this file any other site-specific commands for starting 
VAX LISP. 

To install your system shareable, delete the comment character (!) 
from the beginning of each command between SET NOON and SET ON in the 
default LISPSITE.COM file. 


3.2.1 Defining the LISP System Logical Names 

The following list describes the LISP system logical names and shows 
how to define them. 

• LISP$TIME_ZONE 

Define LISP$TIME_ZONE to indicate your local time zone 
relative to Greenwich Mean Time (GMT). The value can be an 
integer or a floating-point number in the range 0 (inclusive) 
to 24 (exclusive). Floating-point numbers are used when an 
area is not in a full hour time zone, and are specified by the 
format "hour.fraction". To determine your local time zone, 
consult an atlas. 
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Examples: 


$ DEFINE/SYSTEM/EXECUTIVE LISP$TIME_ZONE 4.5 
$ DEFINE/SYSTEM/EXECUTIVE LISP$TIME_ZONE 5 
$ DEFINE/SYSTEM/EXECUTIVE LISP$TIME_ZONE 8 
$ DEFINE/SYSTEM/EXECUTIVE LISP$TIME_ZONE 12.75 
$ DEFINE/SYSTEM/EXECUTIVE LISP$TIME_ZONE 23 


! Newfoundland 
! Boston 
! San Francisco 
! Chatham Island 
! Munich 


NOTE 

This logical name is required. 


• LISP$DAYLIGHT_SAVING_TIME_P 

Define LISP$DAYLIGHT_SAVING_TIME_P to specify whether you are 
on daylight saving time. The values T, TRUE, YES, and 1 mean 
yes; any other values mean no. You should update this logical 
name each time daylight saving time changes. 

In the following example, the NO after the logical name means 
it is not daylight saving time. 

Example: $ DEFINE/SYSTEM/EXECUTIVE - 

LISP$DAYLIGHT_SAVING_TIME_P NO 

• LISP$SHORT_SITE_NAME 

Define LISP$SHORT_SITE_NAME to specify a short string that 
describes your site. This string is returned by the LISP 

SHORT-SITE-NAME function. An example is "Widget Group." 

Example: $ DEFINE/SYSTEM/EXECUTIVE - 

LISP$SHORT_SITE_NAME "Widget Group" 

• LISP$LONG_SITE_NAME 

Define LISP$LONG_SITE_NAME to specify a long string that 
describes your site. This string is returned by the LISP 

LONG-SITE-NAME function. An example is "Super Widget Develop¬ 
ment Group, Widget Corp." 

Example: $ DEFINE/SYSTEM/EXECUTIVE LISP$LONG_SITE_NAME - 

"Super Widget Development Group, Widget Corp." 

If you would like the long site name to occupy several lines, 
you can create a text file for it. Then, refer to the text 
file with the logical name. Suppose, for example, that the 
file SYS$MANAGER:LISPSITE.TXT contained the following text: 
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Super Widget Development Group 
Intelligent Widget Corporation 
One First Street 
Any Town, Massachusetts 01001 

You can define LISP$LONG_SITE_NAME by placing an at sign (@) 
in front of the name of the text file you created. 

Example: $ DEFINE/SYSTEM/EXECUTIVE LISP$LONG_SITE_NAME - 

"@SYS$MANAGER:LISPSITE.TXT" 

• LISP$MACHINE_INSTANCE 

Define LISP$MACHINE_INSTANCE as a string that identifies the 
specific computer on which VAX LISP is running. This string 
is returned by the LISP MACHINE-INSTANCE function. An example 
is "Super Widget VAX-11/785." 

Example: $ DEFINE/SYSTEM/EXECUTIVE LISP$MACHINE_INSTANCE - 

"Super Widget VAX-11/785" 

If this logical name is not defined and you are running 
DECnet, your computer's node name is used as the machine 
instance. 

In the preceding list of system logical names, the two logical names 
LISP$TIME_ZONE and LISP$DAYLIGHT_SAVING_TIME_P are used by the LISP 
function GET-DECODED-TIME, which is described in COMMON LISP: The 
Language. The functions SHORT-SITE-NAME, LONG-SITE-NAME, and MACHINE- 
INSTANCE are described in the VAX LISP User's Guide. 


3.2.2 Installing the Shareable Sections 

If more than one user is on your VAX LISP system, you may want to 
install it as a shareable system. The following explanation describes 
how to install and delete shareable sections and the amount of global 
pages you need to install them. 

You need approximately 5060 global pages to install the VAX LISP/VMS 
image LISP.EXE. You can install this image as you do any other image. 
If you install it, users of the VAX LISP/VMS system share the 
read-only section of the image, reducing physical memory requirements 
and making image activation faster. 

Install LISP.EXE by putting the following two lines in the file 
LISPSITE.COM: 

$ INSTALL := $SYS$SYSTEM:INSTALL /COMMAND_MODE 
$ INSTALL LISP$SYSTEM:LISP/OPEN/HEADER_RESIDENT/SHARED 
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NOTE 

You must surround any installation commands in 
LISPSITE.COM with the SET NOON (do not check for 
errors) and SET ON (check for errors) commands. 

Symbol definitions, as in the preceding example 
(INSTALL := $SYS$SYSTEM:INSTALL), must be local (: = ), 
not global (:==). 


3.3 TUNING THE Al VAXSTATION 

You can tune your AI VAXstation in two ways: 

• By adjusting parameter values in your system parameters file 

• By adjusting authorization quotas in your user accounts 


3.3.1 Recommended System Parameters 

The following sample MODPARAMS.DAT file is for a typical monochrome AI 
VAXstation. The values of these AUTOGEN parameters are recommended 
for optimal performance of VAX LISP on an AI VAXstation with 9 mega¬ 
bytes of memory. 


Sample SYS$SYSTEM:MODPARAMS.DAT File 


Site specific AUTOGEN data file. In a VAXcluster where a 
common system disk is being used, this file should reside 
in SYS$SPECIFIC:[SYSEXE], not a common system directory. 


Add modifications that you wish to make to AUTOGEN's hardware 
configuration data, system parameter calculations, and page, 
swap, and dump file sizes to the bottom of this file. 


CHANNELCNT=2048 
CTLPAGES=500 
SPTREQ=2 000 

MPW_HILIMIT=2500 

MPW WAITLIMIT=2500 


Number of allowed channels 
Used with workstation windows 
Required number of system page table 
entries 

Modified page-list size at which writing 
to free-list page occurs 
Wait-limit number of pages on the 

modified page list; this number must 
be greater than or equal to the 
MPW_HILIMT number or a system 
deadlock will occur 
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MPW_LOLIMIT=5 00 


NPAGEDYN=330000 

PAGFILCNT=1 

PAGEFILE=30000 
PAGEDYN= 4000000 
PHYSICALPAGES=18432 
SWPFILCNT=1 

SWAPFILE=8000 

WSMAX=12000 

WSINC=350 


WSDEC=0 

VIRTUALPAGECNT=30 000 


Writing of the modified page list stops 
when it is less than or equal to the 
MPW_LOLIMIT number 

Size of the non-paged dynamic pool in 
pages 

1 page file; the maximum number of 
page files that can be installed 
Size of a page file in pages 
Size of the paged dynamic pool in pages 
9 megabytes of physical memory 
1 swap file; the maximum number of 
swapping that can be installed 
Size of a swap file in pages 
Maximium working set size 
Amount by which the working set of a 
process is increased by AWSA 
(Automatic Working Set Adjustment) 
Amount by which the working set of a 
process is decreased by AWSA 
Maximum amount of virtual pages 
a process can map 


The following three values are recommended for a VAXstation II/GPX: 


CTLPAGES=850 

SPTREQ=2300 

NPAGEDYN= 450000 


Used with workstation windows 
Required number of system page table 
entries 

Size of the non-paged dynamic pool in 
pages 


NOTE 

These values are only recommended for a 9-megabyte 
system and should not be used on systems with less 
than 9 megabytes of memory. Using these values on 
systems with less than 9 megabytes could prevent your 
workstation from booting. 

The values are valid only for a system that can be 
characterized as a single-use system running primarily 
VAX LISP. Although running only VAX LISP is not a 
requirement, these values tune the system to run VAX 
LISP efficiently and may have an adverse effect on 
systems that heavily use other products concurrently 
with VAX LISP. 

Therefore, you should review the requirements of other 
products and evaluate these recommended values in that 
context. 
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To adjust your system's parameter values: 

1. Add the preceding values to the file SYS$SYSTEM:MODPARAMS.DAT 

2. Reconfigure your system, using the AUTOGEN utility by 
executing the command: 

@SYS$UPDATE:AUTOGEN SAVPARAMS REBOOT 

For details on using the AUTOGEN Utility, see Chapter 11 of the Guide 
to VAX/VMS System Management and Daily Operations . For detailed 
descriptions of the SYSGEN parameters, see the VAX/VMS Utilities , 
Volume 4C. 

Since these parameters are not dynamic, your system will need to be 
rebooted. AUTOGEN will perform an automatic shutdown and reboot when 
it has finished. 


3.3.2 Recommended Authorization Quotas 


The following are recommended authorization quotas for VAX LISP 
accounts on an AI VAXstation: 


WSDEFAULT: 

1024 

WSQUOTA: 

8000 

WSEXTENT: 

18000 

PGFLQUOTA: 

30000 


Default working set size 
Limit for the amount of physical 
memory a user process may lock 
into its working set 
Absolute limit on physical 
memory the system allows the 
process 

Maximum number of pages a user's 
process can use in the system 
paging file 


To adjust these quotas, invoke the Authorize Utility as shown in 
Section 1.4.5 of this manual. See the VAX/VMS Utilities , Volume 4 for 
further information on the quotas. 


3.4 USING PREVIOUS VERSIONS OF VAX LISP 

The files comprising a saved version of VAX LISP are put in a 
subdirectory under the main VAX LISP directory (referred to by the 
logical name LISP$SYSTEM). The subdirectory name uses the VAX LISP 
version number in the format Vvvu, with vv representing the 2-digit 
version and u representing the 1-digit update. For example, Version 
2.2 would be saved in the subdirectory V022. 
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To run a saved version of VAX LISP, you must define the logical name 
LISP$SYSTEM to refer to the subdirectory containing the files of that 
saved version. Then use the standard LISP command to invoke the old 
version of the LISP system. 
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PROBLEM DETERMINATION AND REPORTING 


If an error occurs while you are using VAX LISP/VMS and you believe 
that the error is a result of a defect in the product, you should 
report the error to DIGITAL, using a Software Performance Report (SPR) 
form. In particular, an error message preceded by "Internal error:" 
is caused by the failure of an internal consistency check and should 
be reported. 

Along with the SPR form, you should include: 

• The operating system name and version, which you can obtain 
with the SOFTWARE-TYPE and SOFTWARE-VERSION functions. 

• The version number of VAX LISP/VMS which is part of the 
greeting message when you start VAX LISP. 

• A complete description of the problem. 

• A listing (reduced to the shortest form possible) of the LISP 
program that caused the error. Include initialization files 
or macro definitions that are pertinent. 

• If possible, use the DRIBBLE function (see COMMON LISP: The 
Language) to place the error output in a file and include a 
listing of the file. 
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HOW TO ORDER 
ADDITIONAL DOCUMENTATION 


From 

Call 

Write 

Alaska, Hawaii, 
or New Hampshire 

Rest of U.S.A. 
and Puerto Rico* 

603-884-6660 

800-258-1710 

Digital Equipment Corporation 

P.O. Box CS2008 

Nashua, NH 03061 

* Prepaid orders from Puerto Rico must be placed with DIGITAL's local subsidiary (809-754- 
7575) 

Canada 

800-267-6219 
(for software 
documentation) 

613-592-5111 
(for hardware 
documentation) 

Digital Equipment of Canada Ltd. 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 

Attn: Direct Order desk 

Internal orders 
(for software 
documentation) 

— 

Software Distribution Center (SDC) 

Digital Equipment Corporation 

Westminster, MA 01473 

Internal orders 
(for hardware 
documentation) 

617-234-4323 

Publishing & Circulation Serv. (P&CS) 
NR03-1/W3 

Digital Equipment Corporation 

Northboro, MA 01532 
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